Connect REST API Reference

Connect REST API Reference

In addition to the xCL command language, Xactly Connect objects can be accessed, modified and invoked using a simple to use REST API.

Calling APIs

When calling REST APIs, you will use standard REST patterns as follows:

  • Use HTTP POST method to create objects. This is also the usual way to invoke objects. In most cases, after a successful POST, you will receive a HTTP 201 with the link to the created object in the Location header of the response. This link ends in the ID of the object that was just created. In the abbreviated example below, a POST is used to create a step and the response includes the ID for the newly created step.
Request:
POST /api/connect/v1/steps
{
  // data to create the object
}

Response: 
HTTP 201 with a Location HTTP header representing the URI for the just-created object
Location: /api/connect/v1/steps/9b00f967ccdd4e56bee2970cc16b21e0

No response body
  • Use HTTP GET to retrieve individual instances or collections (lists) of objects. If you have the ID of an object, you can use this to retrieve a full description of that object. It is also used to retrieve many objects of the same type, e.g. after performing a search. For a more detailed description of how to search Xactly Connect collections see the How to Search section below.
Sample Requests:
// Retrieve the steps with the given ID
GET /api/connect/v1/steps/d67227fa5e464ca997fc58decc2a90e2

//  Get a list of audit entries from entry 21 to entry 40
// (defaults for page is zero and for size if 100)
GET /api/connect/v1/audits?page=1&size=20

// search for all pipelines with a name starting with "mypipeline" (case insensitive)
GET /api/connect/v1/pipelines?ql=name==mypipeline*

Response: 
HTTP 200 with a response body
  • Use HTTP PUT method to update an individual object. When doing this, the definition of the entire object should be provided in the body of the request, including the field(s) to be updated. If you omit one of the attributes, it will be updated to the null value. Therefore, you have to make sure to provide all updateable fields in the request body even if the value of the field is not changing. See the definition of the individual REST object (entities) to see which fields are updateable. Upon a successful PUT (update), you will receive a HTTP 204 with no response body.
Request:
PUT /api/connect/v1/steps
{
  // data to update the step
  // all updateable fields should have a value to avoid deleting fields
}

Response:
HTTP 204 with no response body
  • Use HTTP DELETE method to completely remove an object instance from the Connect system. Be extremely careful when using this operation. The HTTP DELETE requires the ID of the object but no request body. Upon a successful deletion you will receive an empty HTTP 204 response.
Request:
DELETE /api/connect/v1/steps/d67227fa5e464ca997fc58decc2a90e2
Response:
HTTP 204 with no response body

Authentication

Xactly Connect APIs provide a standard OAuth2 password grant mechanism for authenticating. Any calls to the APIs require a valid OAuth2 token. To obtain a token (which you can use for the duration of your Connect session) you must authenticate using your valid Connect credentials.
1. Contact support to obtain your unique API Consumer name and Application ID. These will be used during the authentication process.
2. Obtain your Connect username and password for using Connect APIs.
3. Call the API Gateway https://<environment>.xactlycorp.com/api/oauth2/token API to obtain your OAuth token. Use the appropriate domain name to obtain a token for the desired environment as shown in the table below.

Demonstration https://api-demo.xactlycorp.com

Production https://api.xactlycorp.com
Sandbox https://api-sandbox.xactlycorp.com
Implementation https://api-implement.xactlycorp.com 
Sample request: 
POST https://api.xactlycorp.com/api/oauth2/token?client_id={your_client_id}&consumer={your_consumer_name}&api=connect
{
  "username" : "your_connect_username",
  "password" : "your_connect_password"
}

Response:
HTTP 200
{
  "token_type":"bearer",
  "access_token":"your_oauth_token"
}

4. Use the OAuth token to call any /api/connect/v1/** APIs. The Oauth token is placed in the “Authorization” header of the HTTP request.

Sample request with required oauth authorization header:

GET https://api.xactlycorp.com/api/connect/v1/invocations
Authorization: Bearer your_oauth_token

Lists and Pagination

Most Connect API have a way to get a list of resources. For example, you can call GET /api/connect/v1/invocations to get a list of all steps. Because the number of all invocations in the collection can be very high and hard to process, by default such APIs limit the results to the first 100 objects. As such, the APIs support pagination, giving the caller the ability to specify and receive only a subset of all the resources that would otherwise be returned.

Applying pagination to an API requires two query parameters: page and size. Size is the maximum number of elements the caller is expecting in each page that is returned by the service. Page is the (zero-based) page number if you divide the entire collection by pages of that size. For example, if I ask for the portion of the collection with page=2 and size=5, the service will return to me (at most) elements number 10 through 14. Of course if the collection has only 12 elements in it (#0 to #11) then /api?page=2&size=5 will return 2 elements (#10 and #11). If the collection has only 8 elements, then the response to /api?page=2&size=5 will be an empty list.

To provide a enough information for the caller to decide on next steps, some metadata including the values for the requested page and size as well as the actual number of items returned. This way the client can pick up where it left off or make other decisions.

As of April 2017 release, in addition to pagination information, any search-related metadata is also included. If the caller used the “ql”, “orderby” and “reversesort” URL parameters, they will be reflected in the metadata.

As of April 2017 release, we have also added a _links section to list responses with fully formed URLs for related pages of results (i.e. “next”, “prev”, “first” and “last”)

Example:

To retrieve the “second page” of steps, with page being of size 10, you can call

GET /api/connect/v1/steps?page=1&size=10
 
{ 
  "totalElements": 17,   // there are 17 elements total in the collection
  "size": 10,            // page size has been set to 10 by the caller
  "totalPages": 2,       // The totalElements can get divided into 2 pages of size 10
  "last": true,          // this happens to be the last page 
  "number": 1,           // page number has been set to 3 by the caller (zero-based so this is 2nd page)
  "numberOfElements": 7, // total number of elements that could be found in this page
  "first": false         // this is not the first page 
 "content": [
 {
 "createdBy": "apicaller@xactlycorp.com",
 "createdInstant": "2016-09-26T22:28:28.610Z",
 "modifiedBy": null,
 "modifiedInstant": null,
 "version": 1,
 "id": "8a7aa83557686ef90157689d19425362",
 "name": "evaldatejan1",
 "description": null,
 "labels": [],
 "disabled": false,
 "command": "set runtime_auto_date_firstJan *= ToScalar(:auto_date_firstJan)"
 },
 {
 "createdBy": "apicaller@xactlycorp.com",
 "createdInstant": "2017-02-04T06:33:48.708Z",
 "modifiedBy": null,
 "modifiedInstant": null,
 "version": 1,
 "id": "8a7aa8365a07871b015a07d427a46b07",
 "name": "ScheduleUpdated86477",
 "description": "setCurrentTimeVariableNotSet",
 "labels": [],
 "disabled": false,
 "command": "set currentStepState='conditionFalse executed after OnConditionFalse update'"
 },
 {
 "createdBy": "apicaller@xactlycorp.com",
 "createdInstant": "2016-09-29T22:55:55.294Z",
 "modifiedBy": null,
 "modifiedInstant": null,
 "version": 1,
 "id": "8a7aa83557776cbe015778294d9e550f",
 "name": "my_insert_step",
 "description": null,
 "labels": [],
 "disabled": false,
 "command": "INSERT INTO delta.my_temp_table (order_code, item_code)"
 },
 {
 "createdBy": "apicaller@xactlycorp.com",
 "createdInstant": "2016-09-22T00:52:48.979Z",
 "modifiedBy": null,
 "modifiedInstant": null,
 "version": 1,
 "id": "8a7aa835574ef58301574f6172d305db",
 "name": "delete_processed_orders",
 "description": null,
 "labels": [],
 "disabled": false,
 "command": "incent synchronous delete orders processed (BatchNames=(select distinct(batch_name) from staging.order_item))"
 },
 {
 "createdBy": "apicaller@xactlycorp.com",
 "createdInstant": "2016-09-22T00:52:49.723Z",
 "modifiedBy": null,
 "modifiedInstant": null,
 "version": 1,
 "id": "8a7aa835574ef58301574f6175bb05f3",
 "name": "delete_connect_order_staging",
 "description": null,
 "labels": [],
 "disabled": false,
 "command": "delete from staging.order_item"
 },
 {
 "createdBy": "hsawhney@xactlycorp.com",
 "createdInstant": "2017-02-08T05:51:55.785Z",
 "modifiedBy": null,
 "modifiedInstant": null,
 "version": 1,
 "id": "8a7aa8365a1c221c015a1c473f8a1251",
 "name": "s_set_period_end_date",
 "description": null,
 "labels": [],
 "disabled": false,
 "command": "set v_period_end_date = ToDate('2015-01-31')"
 },
 {
 "createdBy": "hsawhney@xactlycorp.com",
 "createdInstant": "2017-02-06T15:03:00.923Z",
 "modifiedBy": null,
 "modifiedInstant": null,
 "version": 1,
 "id": "8a7aa8365a12a7d8015a13f3103b18db",
 "name": "RestTestSchedule-ScheduleUpdated12755",
 "description": "setCurrentTimeVariable",
 "labels": [],
 "disabled": false,
 "command": "set currentStepState='conditionTrue executed by updated step'"
 }]
}

Most of the collections represented by the Connect APIs are searchable through RSQL query syntax. These searchable entities include: Steps, Pipelines, Invocations, Audits, Schedules, Emails, Variables, Iterators. Any GET service that allows a “ql” query parameter allows search.

Searching is done by adding a “ql” query parameter to the URL and supplying a valid RSQL search term(s). For a complete description of all the available options and variations it’s best to look at the RSQL documentation. All string searches are case-insensitive. Some examples are

  • Search for an exact string value for the “name” attribute
    • ?ql=name==myObjectName
  • Search for any value that exists (or does not exist) in a list of possible values for the “name” attribute
    • ?ql=name=in=(name1, anotherName, thirdOne)
    • ?ql=name=out=(name1, anotherName, thirdOne)
  • Search for a string value that includes a given substring (using string wildcard)
    • ?ql=description==*pipeline*
  • Search for a value that has spaces or other non-standard characters (note the double quotes)
    • ?ql=description=="a long description with 'spaces' and such"
  • Search by a date (the format is important … must be ISO8601 yyyy-MM-ddTHH:mm:ss.SSSZ format. “ge” is the same as “>=” and “le” is the same as “<=”.
    • ?ql=createdInstant=ge=2017-01-20T18:12:57.626Z

Caveats and notes:

  • White space: If your ql query term contains spaces, you must use double-quotes around each term. For example: ?ql=description=="a phrase with spaces" and description!= "another phrase"
  • Special Characters: If your query has some “reserved characters” then you must also URL-encode the ql parameter. For example, ?ql=description=="this phrase has # and  ? in it" must be submitted as  ?ql=description=="this%20phrase%20has%20%23%20and%20%20%3F%20in%20it"
  • Double quotes: Currently searching a value that has a double-quote is not supported. For example you will get an error if you try ?ql=description=="bad"search" even if it is URL-encoded. Single quotes are allowed.

Ordering the results based on attribute

This can be done simply by adding an additional “orderby” query parameter. e.g.

  • GET /api/connect/v1/schedules?ql=description==”*pipeline*”&orderby=name

will search for all schedules where the name contains “pipeline” and then return the results in the ascending lexical order of the schedule names. Orderby parameter is ignored if it’s not accompanied by a ql.

Ordering the results in descending order

Dy default, whenever orderby is used, results are returned in ascending order. If you want to reverse the order of the results it can be done simply by adding an additional “reversesort” query parameter. e.g.

  • GET /api/connect/v1/schedules?ql=description==”*pipeline*”&orderby=name&reversesort=true

will search for all schedules where the name contains “pipeline” and then return the results in the descending lexical order of the schedule names. Reversesort parameter is ignored if it’s not accompanied by a orderby.

Interactive Docs

Xactly Connect “Swagger” docs allow users to interactively experiment with Connect’s REST API.

Xactly has deployed Swagger sites for each application pod. Use the pod (or pods) your business has access to. A quick way to determine which pod you have access to is to login to the Incent UI with a web browser and see which server you’ve been redirected to after logging in. Caution: using the “try-me” functionality can potentially change your environment. It’s best to try these functions in Implementation pod or Sandbox.

REST Entities and Attributes